<!--
 Copyright 2010 Andrew Rickmann

 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
 You may obtain a copy of the License at

 http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->
<?php include('header.php'); ?>
<div id="content" class="prepend-top last">
    <div id="main-content" class="prepend-top span-18">
    <h1>Extending Waterwheel with Plugins</h1>
    <p>Waterwheel can be extended by creating plugins.</p>
    <h2>Creating a plugin</h2>
    <p>Creating a new Waterwheel plugin is very easy; however, there are some basic rules you must follow.</p>
    <ol>
    <li>All plugins are classes that extend the <em>plugin</em> class;</li>
    <li>The file containing the class, and only the class, must be named {classname}.plugin.php; and</li>
    <li>The file must be saved inside a sub-directory of the plugins directory.</li>
    </ol>
    <p>The example below shows the most basic plugin that can be created.</p>
    <?php

    //insert the code content from the sample file.
    $sample_file_content = file_get_contents( APPLICATION_PATH . '/plugins/gettingstarted/files/samples/pluginsample.txt'  );
    $geshi->set_source($sample_file_content);
    echo $geshi->parse_code();
    
    ?>
    <p><a href="<?php echo APPLICATION_PATH; ?>/plugins/gettingstarted/files/samples/pluginsample.txt">Download a copy of the sample plugin.</a></p>
    <h2>Interacting with Waterwheel</h2>
    <p>There are two ways in which a plugin can interact with Waterwheel:</p>
    <ul>
	<li>Actions</li>
	<li>Filters</li>
    </ul>
    <p>Actions and filters are both triggered within the Waterwheel code so that plugins can interact with the code at that point.</p>
    <p>To make use of an action or a filter you need to know its name and whether it is an action or a filter.</p>
    <p>To use either you include a function in your plugin class called either <code>action_{action_name}</code> or <code>filter_{filter_name}</code>, for example:</p>
    <?php

    //insert the code content from the sample file.
    $code = 'function action_plugins_loaded(){
    echo "All the plugins are now loaded";
}

function filter_{filter_name}( $input ){
    $input .= "text";
    return $input;
}';
    $geshi->set_source($code);
    echo $geshi->parse_code();

    ?>
    <p>Filters will always have data to pass in to your function, actions might pass data that is useful depending on the action.</p>
    <p>The only difference between an action or a filter is that the filter expects the data to be returned after you have done somthing to it. If you do not return a value an exeption will be thrown and the system will stop.</p>
    <h2>Plugin Settings</h2>
    <p>Waterwheel plugins contain an interface for storing information that is used by your plugin in the database.</p>
    <p>The following example shows how to save settings to the database and retrieve them again.</p>
    <?php

    //insert the code content from the sample file.
    $code = 'function action_example(){

    $mysettingvalue = "London";
    $this->settings->set(\'town\' , $mysettingvalue);

    $mysetting = $this->settings->get(\'town\');

}';
    $geshi->set_source($code);
    echo $geshi->parse_code();

    ?>
    <p>In addition to these examples you can use <code>remove_setting( name )</code> to remove the value or <code>remove_settings()</code> to remove all the settings created by your plugin.</p>

    </div>
    <?php include('plugintopics.php'); ?>
</div>
<?php include('footer.php'); ?>

